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Preface 


This manual introduces the Display PostScript® system extension of Digital’s 
ULTREX Worksystem Software (UWS). The manual describes mainly UWS- 
specific concepts, tasks, and facts that programmers must know to write Display 
PostScript applications for UWS. 

This manual supplements Display PostScript system documentation written 
by Adobe Systems, Inc. This Adobe documentation is included in the UWS 
documentation set and describes the system-independent aspects of the Display 
PostScript system. 


Audience 


The Guide to Developing Applications for the Display PostScript System is in¬ 
tended for experienced UWS application programmers who are familiar with C 
language programming. The Guide assumes that the reader is familiar with the 
PostScript language. In addition, the Guide assumes that the reader has access 
to Display PostScript system documentation from Adobe Systems, Inc., which is 
part of the UWS documentation set 


Organization 

This manual consists of six chapters: 

Chapter 1 introduces the Display PostScript system and lists the capabilities it 
adds to UWS. 

Chapter 2 describes the main components of the Display PostScript system and 
summarizes key concepts. 

Chapter 3 explains how to start writing applications for the Display PostScript 
system and presents a simple example program. 

Chapter 4 presents advanced concepts and tasks. 

Chapter 5 describes the UWS-specific header file of the Display PostScript system 
Client Library and describes each UWS-specific Client Library routine. 

Chapter 6 describes X-specific operators provided by UWS. 


vii 





Related Documents 


The following UWS manuals help you understand the portions of UWS that 
interact with the Display PostScript system extension. 

• Guide to the Xlib Library: C Language Binding 

• Guide to VAX C 

The X Window System: C Library and Protocol Reference , published by Digital 
Press, explains the X Window System, which UWS implements. 

The following manuals from Adobe Systems, Inc., are included in the UWS 
documentation set; they describe system-independent aspects of the Display 
PostScript system. 

• PostScript Language Perspective for Software Developers 

• Display PostScript System Client Library Reference Manual 

• PostScript Language Extensions for the Display PostScript System 

• PostScript Language Color Extensions 

• Display PostScript System pswrap Reference Manual 

The following books, published by Addison-Wesley Publishing Company, Inc., help 
you understand the PostScript language: 

• PostScript Language Reference Manual 

• PostScript Language Tutorial and Cookbook 

• PostScript Language Program Design 


Conventions 


The following typographical conventions are used in this manual: 


Convention 

Meaning 

this typeface 

this typeface 

In examples, a horizontal ellipsis means that addi¬ 
tional parameters, values, or other information can be 
entered, that preceding items can be repeated, or that 
optional parameters have been omitted. 

In text and examples, all directory names, file names, 
and code samples appear in this typeface. 

In text and examples, PostScript language operators 
and X-specific operators appear in this typeface. 
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Chapter 1 

Introduction to the Display PostScript System 


To display or print graphics, an application must have an imaging model, a set 
of rules for describing pictures and text. One of the most popular imaging models 
is that of the PostScript page-description language, from Adobe Systems, 

Inc. Originally developed for hardcopy output devices, such as laser printers, the 
PostScript language imaging model has been adapted for bitmap displays through 
Adobe’s Display PostScript system. 

Digital’s ULTRIX Worksystem Software (UWS) implements the imaging 
models of the X Window System and the Display PostScript system. UWS 
applications can mix X and PostScript language imaging calls, even within a 
single window, using a single network connection to an X server. This manual 
introduces the Display PostScript system and shows how to develop UWS 
applications that use it. 


1.1 What Is the Display PostScript System? 

The Display PostScript system is software that extends the PostScript imaging 
model to bitmap display systems. With the Display PostScript system, you can 
design and write applications in a general-purpose language like C, yet describe 
their images and text using the device-independent PostScript imaging model. 


1.2 PostScript Language Imaging Capabilities 

You are probably familiar with the capabilities of X imaging. The following 
capabilities are found in PostScript language imaging but not in X imaging: 

• Coordinate system that can be moved, rotated, and scaled 

• Bezier curves 

• Device-independent color model with dithered (approximated) colors 

• Text that can be scaled and rotated 

• Image operators for scanned images 

(scaling, rotating, transformations, gray-scale manipulation) 
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1.3 Display PostScript System in UWS 


The Display PostScript system is a system-independent client/server architecture 
that can be implemented on a variety of windowing systems. In this architecture, 
the server consists mainly of a PostScript interpreter, which executes PostScript 
language code that displays images on a user’s screen. The client is an 
application that communicates with the server through a set of routines known 
as the Client Library. 

UWS implements the Display PostScript system as an extension to the X Window 
System, on which UWS is based. The Display PostScript system server is an 
extension to the X server; the Client Library is an extension to Xlib. The Display 
PostScript system extension of UWS lets a C language application display images 
in an X window by calling functions that send PostScript language code. 

Figure 1-1 shows the UWS implementation of the Display PostScript system. 
(For brevity, this manual often refers to this implementation as XDPS.) For 
more information about how UWS implements the Display PostScript system, see 
Chapter 2. 

Figure 1-1: Display PostScript System as Implemented in UWS 
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1.4 Summary of Documentation 

To understand and use the Display PostScript system in UWS, you must be 
familiar with these subjects: 

• The ULTRIX operating system 

• The C programming language 

• UWS programming 

• The PostScript language 
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• The system-independent aspects of the Display PostScript system 

• The UWS-specific aspects of the Display PostScript system 

This manual describes mainly the UWS-specific aspects of the Display PostScript 
system. To learn about more general aspects, see the Display PostScript System 
Client Library Reference Manual . 

Table 1-1 briefly describes UWS manuals and other books that help you 
understand the Display PostScript system in UWS. 


Table 1-1: Summary of Display PostScript Documentation 


To learn about 

Read this book 

Where to find it 

UWS-specific aspects of the Display 
PostScript system 

Guide to Developing Applications for 
the Display PostScript System 

UWS 

documentation 
set (docset) 

System-independent introduction to 
the Display PostScript system 

PostScript Language Perspective for 
Software Developers 

UWS docset 

System-independent reference for 
the Display PostScript system 

Display PostScript System Client 
Library Reference Manual 

UWS docset 

PostScript language 

PostScript Language Reference 
Manual , PostScript Language 

Tutorial and Cookbook , PostScript 
Language Program Design 

Most technical 
bookstores 

PostScript language as extended for 
the Display PostScript system 

PostScript Language Extensions for 
the Display PostScript System 

UWS docset 

PostScript language as extended for 
color support 

PostScript Language Color 

Extensions 

UWS docset 

Converting PostScript procedures 
into C-callable routines 

Display PostScript System pswrap 
Reference Manual 

UWS docset 

Xlib programming 

Guide to the Xlib Library: C 
Language Binding , X Window 

System: C Library and Protocol 
Reference 

UWS docset 
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Chapter 2 

Components and Concepts 


Even for UWS programmers who are familiar with the PostScript language, the 
Display PostScript system for UWS introduces new concepts. For instance, some 
familiar terms such as “client,” “context,” and “state” take on new meanings. 

This chapter summarizes components and concepts of the Display PostScript 
system. Some of these topics are system-independent; others are system- 
specific. In this manual, the term “system-independent” refers to components 
and concepts found in all implementations of the Display PostScript system. 
“System-specific” refers to components found in only some implementations of the 
Display PostScript system and whose exact names and capabilities vary among 
implementations. 

The Display PostScript system for UWS is the “system” being described in this 
manual, so “UWS-specific” and “system-specific” mean the same thing here. 

Note that some UWS-specific components are also “X-specific”: they exist only in 
X-based implementations of the Display PostScript system. 

This chapter emphasizes mainly UWS-specific concepts and components. For a 
more general introduction to the Display PostScript system, see the PostScript 
Language Perspective for Software Developers and the Display PostScript System 
Client Library Reference Manual . 


2.1 Components 

The Display PostScript system consists of three main components: 

• PostScript interpreter 

• Client Library 

• The pswrap translation program 

In UWS, the PostScript interpreter resides on the X server; the Client Library 
is linked with the X client. The client and server can reside on the same 
workstation or on different workstations connected by a network. 


2.1.1 PostScript Interpreter 

In UWS, the PostScript interpreter is an X server extension that executes 
PostScript language code sent from applications. The interpreter implements 
the full PostScript language, including operators for color and display. You can 
imagine the PostScript interpreter as a PostScript printer. Unlike a printer, 
however, the interpreter can concurrently execute several “jobs.” 
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2.1.2 Client Library 

The Client Library is the set of C language routines through which applications 
communicate with the PostScript interpreter. The Client Library routines 
communicate with the PostScript interpreter by calling Xlib routines and low- 
level Display PostScript system routines implemented as extensions to Xlib. Note 
that, although there is currently no toolkit interface to Display PostScript system 
itself, applications that use the system can use toolkit interfaces to X as usual. 

NOTE 

Except where noted, the term "application” means a UWS application 
program that uses the Display PostScript system. 

The Client Library routines and data structures that make up the application 
programming interface to the Display PostScript system are defined in six 
header files. Only one of these six files is X-specific: dpsXclient .h. For more 
information about dpsXclient .h, see Chapter 5. 


2.1.3 The Translation Program: pswrap 

The pswrap translator is a program that converts procedures written in the 
PostScript language into routines that can be called from applications written in 
C. The converted routines are called wrapped procedures, or wraps. In UWS, 
pswrap is installed in the directory /usr/bin. For information on using 
pswrap, see the Display PostScript System pswrap Reference Manual . 

A special set of ready-to-call wraps is included in the Client Library; most of these 
wraps send a single PostScript operator. These single-operator wrapped proce¬ 
dures are called singleops. For more information on singleops, see Chapter 5 
and the Display PostScript System Client Library Reference Manual. 


2.2 Concepts 

Before you can write an application that uses the Display PostScript system, 
you should understand a few essential concepts. This section introduces those 
concepts. 


2.2.1 Contexts 

The term "context” is familiar to X programmers. But in the Display PostScript 
system, a context is not an X Graphic Context, or “GC.” Instead, a context is a 
destination to which an application sends PostScript language code. A PostScript 
context is either an execution context or a text context. 

NOTE 

Except where noted otherwise, the term "context” refers to a PostScript 
context; the X Graphic Context is referred to as the "GC” or as the 
"X Graphic Context.” Also, except where noted, the term "context” 
includes both execution contexts and text contexts. 
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2.2.1.1 Execution Context 

An execution context is a destination that executes PostScript language code sent 
from an application. In UWS, that destination is the PostScript interpreter of the 
X server. Just as the interpreter is like a PostScript printer, an execution context 
is like a print job. 

In UWS, a PostScript execution context is usually associated with an X display, an 
X drawable, and a GC. The PostScript execution context uses only the following 
fields of the GC: 

clip_mask 

clip_x_origin 

clip_y_origin 

plane_mask 

subwindow_mode 

The Display PostScript system in UWS treats the X drawable and GC as part 
of the PostScript graphics state, a data structure that defines how PostScript 
operators execute. (For information about the PostScript graphics state, see the 
PostScript Language Reference Manual .) 


2.2.1.2 Text Context 

A text context is a destination that does not execute the PostScript language 
input it receives from an application. For example, the destination might be a 
text file or an ULTRIX stream, such as stdout. The destination is specified 
in the text-handling routine that the application assigns when creating the text 
context. 

Sending PostScript language input to a text context provides a way to get a 
printable copy of input that would otherwise be sent to an execution context. This 
capability is particularly useful in debugging applications. 

NOTE 

In this manual, except where noted otherwise, the term “input” means 
input to a context on the server, not to an application on the client. 
Conversely, “output” means output from a context. 


2.2.2 Context Record and DPSContext Handle 

All contexts reside on the server. However, on the client, each context is rep¬ 
resented by a context record, whose data type is DPSContextRec. The 
DPSContextRec stores the attributes of the context, for instance, the pointer to 
its error-handling routine. 

Applications do not access the DPSContextRec directly. Instead, when calling 
Client Library routines, applications explicitly or implicitly pass a pointer to 
the DPSContextRec. This pointer, or “handle,” is of type DPSContext and is 
known as the DPSContext handle. 
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2.2.3 Context Status 

An execution context can be in any of several states. For example, a context 
might be ready to execute, or it might be waiting for PostScript language code 
from the application. An application can monitor the execution state of a context 
by requesting context status events from the server. A context status event is 
an X event whose integer value represents the execution state of the context: its 
context status. Each time the context status changes, the server generates a 
context status event. 

Although the server generates context status events, it does not automatically 
send them. To receive context status events, an application must explicitly set the 
context status mask, a data structure associated with each execution context. 
(For more information about the context status mask, see the description of the 
Client Library routine XDPSSetStatusMask in Chapter 5.) 


2.2.4 Current Context 

A typical application creates only one context. For this reason, the Display 
PostScript system lets an application specify one context as the current context. 
The current context is the default context for Client Library routines that take an 
implicit context argument. 


2.2.5 Space 

On the server, each execution context has virtual memory (VM) known as a 
space. In addition to the space of each execution context, there is shared VM, 
which is shared among all execution contexts of a server. 

If an application creates multiple contexts, it can make them share a single space, 
thereby simplifying communication among them. 


2.2.6 Identifiers 

In UWS, execution contexts and spaces are associated with X resources on the 
server. For this reason, execution contexts and spaces have, in addition to their 
PostScript language ID, an X resource ID (XID). Application programmers, 
however, seldom need to reference these XIDs. 


2.2.7 Coodinate Systems 

The Display PostScript system and X both use a coordinate system for imaging, 
but the coordinate system used by the Display PostScript system differs from that 
used by X. This section briefly explains both coordinate systems and explains how 
they interact in UWS. 

Each X window has a coordinate system whose origin is always the upper left 
comer. From this X origin, x increases from left to right; y increases from top to 
bottom, as shown in Figure 2-1. 
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Figure 2-1: X Coordinate System 
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The origin used by the Display PostScript system is called the user space 
origin. Unlike the X origin, the user space origin can be specified. 

From the initial user space origin, x increases from left to right (as in X), but 
y increases from bottom to top, as shown in Figure 2-2. (For more information 
about user space, see the PostScript Language Reference Manual ). 
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Figure 2-2: User Space Coordinate System Used by the PostScript Language 
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In UWS, the initial user space origin is offset from the X origin. That is, applica¬ 
tions specify the initial user space origin as a point in the X coordinate system, as 
shown in Figure 2-3. 

In this figure, an application has created a window measuring 300 x 300 pixels. 
The application has specified the X coordinates [0,300] (the window’s lower left 
corner) as the initial user space origin. Thus, the window’s lower left comer 
becomes the origin [0,0] of the user space coordinate system. 
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Figure 2-3: Initial User Space Origin Is Offset from X Origin 
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When an X window is resized, its user space origin moves according to the bit 
gravity of the window. For more information on how resizing a window affects its 
user space origin, see Section 4.5. 


Components and Concepts 2-7 









Chapter 3 

Getting Started 


This chapter shows you how to develop a typical application that uses the 
Display PostScript system. It describes the steps you follow to develop a typical 
application and describes the steps that a typical application performs. The 
chapter then presents a sample application. 

Before You Start 

Before reading this chapter, be sure you understand the following components 
and concepts, covered in Chapter 2: 

• PostScript interpreter 

• Client Library 

• The pswrap translation program 

• PostScript context 

If you understand these, you are ready to start. 


3.1 Developing a Typical Application 

To develop a typical application, you follow six main steps, as shown in 
Figure 3—1. (Steps 3 through 5, however, take much less time than the others.) 

O Design the application. 

© Write the main C-language module and any custom PostScript language 
procedures that the application calls. 

© Convert the custom PostScript language procedures into C-callable routines 
by running the pswrap translation program. 

© Compile the C-language code with: 

• The output files from pswrap 

• The X header files 

• The header file dpsXclient. h and any optional XDPS header files, like 
dpsops .h 

© Link the resulting object file with the X libraries and with the Client Library. 
© Run and debug the executable application. 
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Figure 3-1: Developing a Typical Application 
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Step 1: Design the Application 

In UWS, Display PostScript system applications are written in C and send 
PostScript language code to a context, usually an X server. But to design an 
application, you must make several decisions. For example, you must decide: 

• Whether to code mostly in C or mostly in the PostScript language 

• Whether to create one PostScript context or several 

• Whether to send PostScript language code by custom wraps, by singleops, as 
text, or by a combination of these methods 

For a typical simple application, the following design decisions are usually best: 

• Code mostly in C; use the PostScript language for imaging-related tasks only. 

• Create only one PostScript context. 

• Send lengthy PostScript language segments as custom wraps; send single 
PostScript language statements as singleops. 
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A complete discussion of application design is beyond the scope of this book. To 
help you see and understand how design decisions affect XDPS applications, the 
UWS distribution kit includes source files for several sample applications. For 
more information about these sample applications, see Section 3.5. 

Step 2: Write Your C Code and PostScript Language Code 

After you have designed your application, you write the C-language code and the 
PostScript language procedures that your application sends. 

(It is also possible to write applications that read PostScript language code from 
the user’s keyboard or from a file. For a sample program of this type, see the 
program DPStest. By default, the source files for DPStest are installed in the 
directory /usr/examples/dps/dpstest. For instructions on running the 
program, see Section 3.5. 

Step 3: Convert Your PostScript Language Procedures 

If you have written any PostScript language procedures for your application, you 
should convert them to wraps, that is, to routines that can be called from your 
C-language code. To convert the PostScript language procedures, you process 
them with the pswrap translation program. 

For each PostScript language input file, pswrap can produce two output files: 
a C-callable procedure and an associated header file. For information on using 
pswrap, see the Display PostScript System pswrap Reference Manual. 

Steps 4 and 5: Compile and Link 

After you have converted your PostScript language procedures to C-callable 
routines, you compile and link your source files. That is, you compile your main 
C-language file with: 

• The output files from pswrap 

• The X header files 

• The dpsXclient. h header file and, optionally, other Client Library header 
files 

You link your application with the Client Library and with the X libraries. (For 
instructions on compiling and linking XDPS applications, see Section 3.4.) 

Step 6: Run and Debug Your Application 

You are now ready to run and debug your application. 


3.2 Basic Application Requirements 

All applications send PostScript language statements to a context. Typically, 
the context is an execution context—in XDPS, the PostScript interpreter of an X 
server. Most XDPS applications perform three main steps: 

1. Initialization 

2. Communication 

3. Termination 
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Step 1: Initialization 

Typically, to initialize an XDPS application, you perform three steps: 

1. Establish communication with an X server, create a window, and create a GC. 

2. Create a PostScript execution context by calling an X-specific Client Library 
routine such as XDPSCreateSimpleContext. (For more information on 
creating contexts, see the descriptions of XDPSCreateSimpleContext and 
XDPSCreateContext in Chapter 5.) 

3. Perform any additional X-specific initialization, such as mapping the window. 

Step 2: Communication 

After initializing, most XDPS applications call custom wraps, singleops, or 
other Client Library routines to send text and PostScript language state¬ 
ments to a context. For example, to send information to a context, an ap¬ 
plication might either call a custom wrap or call one of two Client Library 
routines: DPSWritePostScript (for PostScript language statements) or 
DPSWriteData (for data). 

To process text or errors from a context, the Client Library calls the text-handling 
routine or error-handling routine that the application assigned when creat¬ 
ing the context. The Client Library defines a default text-handling routine 
(DPSDefaultTextBackstop) and a default error-handling routine 
(DPSDefaultErrorProc ). Although these routines are called default routines, 
to use them you must specify them explicitly when creating a context. For more 
information on the default routines, see their descriptions in Chapter 5. 

Step 3: Termination 

Terminating a typical XDPS application is like terminating any other typical X 
application. When you terminate an application, the X Window System destroys 
the application’s contexts, their spaces, and any other X resources belonging to 
the application. 


3.3 Sample Application: examplemain 

This section presents examplemain, a simple program that shows the fun¬ 
damentals of XDPS programming. The program uses the Display PostScript 
system to paint a shaded square in a window of the user’s screen, as shown in 
Figure 3-2. 
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Figure 3-2: Output of the examplemain Program 



The examplemain program uses the Xlib interface to X, calls a custom wrap 
to pick the shade of gray for painting, and calls a Client Library single-operator 
procedure to do the actual painting. 

There is more than one way to program almost any XDPS application. To see a 
different approach to essentially the same sample application presented in this 
section, see the section “Example Application Program” in the Display PostScript 
System Client Library Reference Manual. 

3-3.1 What the Sample Application Does 

The sample application examplemain performs the following operations: 

1. Connects the client to an X server with XOpenDisplay 

2. Creates a window with XCreateSimpleWindow 

3. Selects X event types Expose and ButtonPress with XSelect Input 
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4. Creates a Display PostScript execution context with 
XDPSCreateSimpleContext, using the default text handler, the default 
error handler, and the default GC 

5. Displays the window with XMapWindow 

6. Chooses the shade of gray for painting, with a custom wrapped PostScript 
language procedure named ChooseGray 

7. Sets the shade of gray with DPS set gray, a singleop from the Client Library 

8. Paints a gray square with the singleop DPSrectfill each time an Expose 
event is received and exits when a ButtonPress event is received 

9. Destroys the context and space with DPSDestroySpace, and then closes 
the display connection and exits 

Unlike a more complete application, examplemain does not handle resizing of 

the X window. (For information about window resizing in XDPS applications, see 

Section 4.5.) 


3.3.2 The Main Code 

Example 3-1 is a complete listing of examplemain . c, the main C language file 
of the sample application. 

Example 3-1: Sample Application: examplemain 


/* 

* examplemain.c — Simple X application that uses the Display PostScript 

* system to draw a shaded square in a window, then exits when the user 

* clicks the mouse. 

*/ 

finclude <stdio.h> 

#include <Xlib.h> /* Standard X Window C-language library */ 

#include <dpsXclient.h> /* X interface to DPS Client Library */ 

#include <dpsops.h> /* Declarations of singleops */ 

#include "examplewraps.h u /* Interface to wrapped PostScript language code*/ 


(continued on next page) 
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Example 3-1 (Cont.): Sample Application: examplemain 


main () 

{ 


Display *dpy; 

/* 

An X display */ 

Window window; 

/* 

A window of the X display */ 

DPSContext context; 

/* 

A single PostScript context */ 

float grayLevel; 

/* 

The shade of gray for the square */ 

XEvent event; 

/* 

An X event */ 

void TextOut(); 

/* 

Forward declaration */ 

void FatalError(); 

/* 

Forward declaration */ 


/* 

* Open a connection to the X display specified in the argument 

* to the XOpenDisplay routine. The NULL argument causes 

* XOpenDisplay to open a connection to the display specified 

* by the DISPLAY variable of the user's environment. 

*/ 

dpy = XOpenDisplay(NULL); 

/* 

* If unable to open the display, return an error message and 

* exit immediately. 

*/ 

if (dpy == NULL) 

FatalError("Can't open display.\n"); 

/* 

* Create a window on the X display. When mapped, the window will be 

* 10 pixels from the left edge and 20 pixels from the upper edge. 

* The window will be 800 pixels high by 800 pixels wide, with a 

* black border 1 pixel wide and a white background. 

*/ 

window = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy), 

10, 20, 800, 800, 1, 

BlackPixel(dpy, DefaultScreen(dpy)), 
WhitePixel(dpy, DefaultScreen(dpy))); 

/* 

* Select the X event types that the window accepts from 

* the X server. The window accepts Expose events and 

* ButtonPress events. 

*/ 

XSelectlnput(dpy, window, ExposureMask | ButtonPressMask); 

/* 

* Create a PostScript execution context to draw in the window. 

* The origin of the context's coordinate grid is the point (0, 800) 

* of the window. The origin is therefore the bottom left corner 

* of the window (the typical origin for a PostScript context). 

*/ 

context = XDPSCreateSimpleContext(dpy, window, 

DefaultGC(dpy, DefaultScreen(dpy)), 
0, 800, 

TextOut, DPSDefaultErrorProc, NULL); 

/* 

* If unable to create the context, return an error message 

* and exit immediately. 

*/ 

if (context == NULL) 

FatalError("DPS refused to create a context.\n"); 

/* 

* Map the window—that is, make it appear on the display. The 

* window will appear only after the window manager of the X server 

* is free to process the mapping request. When the window appears, 

* the context receives an Expose event as notification. 

*/ 

XMapWindow(dpy, window); 

/* 

* Generate a random number that corresponds to the shade of gray 

* (the graylevel) to be used when painting. To generate this number, 

* call the ChooseGray routine, which is exported from the 

* examplewraps.c file. ChooseGray sends wrapped PostScript 

* language code to the context, which then executes the code. 

*/ 


(continued on next page) 
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Example 3-1 (Cont.): Sample Application: examplemain 


ChooseGray(context, SgrayLevel); 

/* 

* Set the current graylevel to the shade of gray chosen by 

* ChooseGray. Setting the graylevel does not cause any painting; 

* so you can set the graylevel even if the window 

* has not yet appeared. 

*/ 

DPSsetgray(context, grayLevel); 

/* 

* Wait for events from the X server; process each one received. 

* For each Expose event, paint the same gray square in the same 

* place on the display. To do this, call the DPSrectfill routine, 

* a single-operator wrapped procedure declared in dpsops.h, a 

* DPS Client Library header file. The bottom left corner of 

* the square is 100 points above the origin and 100 points to 

* the right of it. Each side of the square is 300 points. 

* 

* When a ButtonPress event is received, exit the event-processing loop. 
*/ 

for (;;) { 

XNextEvent(dpy, &event); 
if (event.type == Expose) { 

DPSrectfill (context, 100.0, 100.0, 300.0, 300.0); 

} else if (event.type == ButtonPress) { 
break; 

} 

} 

/* 

* Exit in an orderly manner. First, destroy the context by 

* destroying its space (its memory). Next, destroy 

* the window. Finally, close the connection to the X display. 

*/ 

DPSDestroySpace(DPSSpaceFromContext(context)); 

XDestroyWindow(dpy, window); 

XCloseDisplay(dpy); 

} 

/* 

* Output procedure for ordinary text messages from the context. 

* Output is sent directly to standard error. 

*/ 

void TextOut(context, buffer, count) 

DPSContext context; 
char ^buffer; 
unsigned count; 

{ 

fwrite(buffer, 1, count, stderr); 
fflush(stderr); 

} 

/* 

* Error procedure. The application has encountered an error 

* from which it cannot recover, so exit immediately. 

*/ 

void FatalError(msg) 
char *msg; 

{ 

fprintf(stderr, msg); 
exit (1); 


3.3.3 Source File for Wrap 

Example 3-2 is a complete listing of examplewraps .psw, the PostScript 
language source file for the wrapped procedure called by the sample application 
examplemain. 
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Processing examplewraps .psw with the pswrap translator produces two 
output files: examplewraps . c and examplewraps . h. These output files 
must then be compiled with examplemain. c. 

Example 3-2: Source File for Wrap Called by examplemain 


/* 

* examplewraps.psw — source file for wrapped PostScript language procedure 

* 

* This is an example of PostScript language code to be converted to 

* Client Library calls by pswrap. 

* 

* This PostScript language routine, ChooseGray, generates a random number that 

* corresponds to the graylevel (shade of gray) to be used when the Display 

* PostScript system paints. Note that the PostScript operator rand always 

* generates the same sequence of random numbers. So each time 

* the program examplemain runs, ChooseGray chooses the same graylevel. 

*/ 


defineps ChooseGray (DPSContext ctx| float ^result) 

rand % Pick a random number between 0 and 2*31 

2 31 exp % 2*31 

div % Random number between 0.0 and 1.0 

result % Return result, 

endps 


1 . 


3-3.4 Running examplemain 

By default, all the program-specific files needed to compile, link, and run 
examplemain are installed in the /usr/examples/dps/gray-square 
directory of your system. For instructions on compiling and linking, see 
Section 3.4. 


3.4 Building XDPS Applications 

After you code an application, you build it by compiling and linking it. This 
section describes how to build an application. It assumes that you are using 
the ULTRIX make utility. (For more information, see make ( ) in the ULTRIX 
Reference Pages.) 

This section includes a complete makefile for the examplemain program 
presented in Section 3.3.2. 


3.4.1 Including Header Files 

Before building an XDPS application, make sure that the main source module 
includes the appropriate X header files and the UWS-specific Client Library 
header file, dpsXclient .h. 

The dpsXclient . h file is the only Client Library header file that all XDPS 
applications must include. It, in turn, includes all other Client Library header 
files, except psops . h, dpsops . h, and dpsexcept. h. 

If your application calls singleops, you should also include psops .h or 
dpsops .h, or both, depending on which defines the singleops that your 
application calls. If your application uses the exception handling capability 
of the Display PostScript system, you must also include dpsexcept. h. (Not to 
be confused with error handling, exception handling is an advanced capability 
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that few applications require. For more information, see the Display PostScript 
System Client Library Reference Manual .) 


3.4.2 Compiling 

You compile the main C-language module of your XDPS application with: 

• The X header files—for example, XI ib. h 

• The dpsXclient. h header file 

• The psops.h and dp sops . h header files (if application calls singleops) 

• The output files from pswrap (if application calls custom wraps) 

The Display PostScript system header files (among them, dpsXclient .h, 
psops . h, and dpsops .h) are installed in the directory /usr/include/DPS. 
To automatically include these files at compilation, add the following statement to 
your makefile: 

CFLAGS = -I/usr/include/DPS 

The option -I/usr/include/DPS causes the ULTR1X C compiler to search for 
include files in /usr/include/DPS. 


3.4.3 Linking 

You link your XDPS application with the following libraries, in the order listed: 


Library 

Linker option 

Client Library 

-ldps 

Xlib extensions for Display PostScript system 

-lXext 

DECwindows toolkit library 

-ldwt 

Xlib library 

-1X11 

ULTRIX math library 

-lm 


3.4.4 Invoking pswrap from a Makefile 

Your makefile can automatically convert PostScript language procedures to 
C-callable routines by running the pswrap translation program. For example, if 
the PostScript language procedures have filenames ending in .psw, the following 
make statements convert the procedures automatically: 

.SUFFIXES: $(.SUFFIXES) .psw .h 
.psw.o: $*.psw 

${P SWRAP} -o $ *.c $*.psw 
$(CC) $(CFLAGS) -c $*.c 
rm $ *.c 

.psw.h: $*.psw 

${PSWRAP} -h $*.h $*.psw > /dev/null 
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3.4.5 A Sample Makefile 

Example 3-3 shows a complete Makefile that builds the examplemain program 
presented earlier in this chapter. 


Example 3-3: Makefile for examplemain 


# @(#)Makefile 1.5 ULTRIX 9/2/88 
DESTDIR= 

EXAMPLETOPDIR=${DESTDIR}/usr/examples/dps 
EXAMPLESUBDIR=${EXAMPLETOPDIR}/gray-square 

INSTALLLIST = Makefile examplemain.c *.psw 

OBJS - examplemain.o examplewraps.o 

P SWRAP= ${DESTDIR}/usr/bin/pswrap 

.SUFFIXES: $ (.SUFFIXES) .psw .h 
.psw.o: $*.psw 
${P SWRAP} -o $*.c $ *.psw 
$(CC) $(CFLAGS) -c $*.c 
rm $ * . c 

.psw.h: $*.psw 

${PSWRAP} -h $*.h $*.psw > /dev/null 
.SUFFIXES: .uil .uid 

CFLAGS = -g -1${DESTDIR}/usr/include/Xll -1${DESTDIR}/usr/include/DPS \ 
-1${DESTDIR}/usr/include -I. 

LIBS = ${DESTDIR}/usr/lib/libdps.a \ 

${DESTDIR}/usr/lib/libXext.a \ 

${DESTDIR}/usr/lib/libdwt.a \ 

${DDIFROOT}/usr/lib/libddif.a \ 

${DESTDIR}/usr/lib/libXll.a \ 

-lm 

all: examplemain 

examplemain: $(OBJS) 

$(CC) -o examplemain $(OBJS) $(LIBS) 

examplemain.o: examplemain.c examplewraps.h 

clean: 

rm -f *.o examplemain examplewraps.[ch] \#* core 

clobber: clean 
-rm -f * 

relink:: 

rm -f examplemain 
relink:: all 
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3.5 More Sample Applications 

In addition to examplemain, the UWS software includes source listings of 
several other sample XDPS applications. 


3.5.1 Examples Contrasting Design Approaches 

UWS includes source listings and makefiles for four related sample programs: 
calcO, calcl, calc2, and calc3. Each of these sample programs is an 
implementation of the same application: a desktop calculator. Although all four 
programs present a similar user interface (shown in Figure 3-3), the source code 
of each program shows a different approach to XDPS application design. 

Figure 3-3: Output of the Sample Calculator Programs 
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For the location of the sample calculator programs, see Table 3-1, which lists and 
describes the sample Display PostScript system applications included in UWS. 


Table 3-1: Online Sample Programs 


Program Name 

Description 

Where to find it 

calcO 

Calculator coded mainly in C, with 
one window and one context 

/usr/examples/dps/calcO 

calcl 

Calculator coded mainly in the 
PostScript language, with one 
window and one context 

/usr/examples/dps/calcl 

calc2 

Calculator coded mainly in C, with 
multiple windows and one context 

/usr/examples/dps/calc2 

calc3 

Calculator coded mainly in C, 
with multiple windows, multiple 
contexts, and intercontext 
communication 

/usr/examples/dps/calc3 

DPStest 

Executes PostScript language 
statements entered from the 
keyboard 

/usr/examples/dps/dpstest 


(continued on next page) 
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Table 3-1 (Cont.): Online Sample Programs 

Program Name Description 


Where to find it 


examplemain 

psclock 

psdraw 


pyro 


Displays a gray square generated 
from a custom wrap and a singleop 

An implementation of xclock that 
uses the Display PostScript system 

A graphic editor that paints 
PostScript language images; a 
complex sample application 

Displays fireworks generated from 
custom wraps 


/usr/examples/dps/gray-square 
/usr/examples/dps/psclock 
/usr/examples/dps/psdraw 

/usr/examples/dps/pyro 


3.5.2 Running the Sample Applications 

To run one of the sample applications, you must first build it by following these 

steps: 

1. Log on to your system and find the subdirectory storing the sample 
application. 

2. Copy the entire contents of that subdirectory to a subdirectory in your 
account. (Note that the sample programs calcO, calcl, calc2, and 
calc3 must be copied to sibling directories, that is, to subdirectories at the 
same level of the file system.) 

3. Set your working directory to the subdirectory that received the copies in Step 

2 . 

4. Invoke the ULTREX make utility by entering the command make at the 
system prompt. (The make utility compiles and links the program. Note that 
for the sample application psdraw, you must enter make install instead 
of make. For information, see make ( ) in the ULTRIX Reference Pages.) 

You can then run the program by entering its name at the system prompt. For 

more information on building XDPS applications, see Section 3.4. 


3.6 Summary of Basic Tasks 

Table 3-2 lists common XDPS programming tasks and shows the operators and 
Client Library routines for performing each task. 


Table 3-2: Summary of Basic Tasks 
To do this task... 

Create an execution context 

Create a text context 

Use the default text handler 

Use the default error handler 


Use these routines and operators 

XDPSCreateSimpleContext or 
XDPSCreateContext 

XDPSCreateTextContext 

DPSDefaultTextBackstop 

DPSDefaultErrorBackstop 

(continued on next page) 


Getting Started 3-13 







Table 3-2 (Cont.): Summary of Basic Tasks 


To do this task... 

Use these routines and operators 

Find the space of a context 

DPSSpaceFromContext 

Find the default user space origin 

currentXo f f s et 1 

Set the default user space origin 

setXoffset 

Find the GC of a context 

currentXgcdrawable 

Set the GC of a context 

setXgcdrawable 

Restart a context 

DPSResetContext 

Find the current drawable 

currentXgcdrawable 

Set the current drawable 

setXgcdrawable 

Convert between PostScript language IDs 

XDPSXIDFromContext 

and XIDs 

XDPSXIDFromSpace 

XDPSContextFromXID 

XDPSSpaceFromXID 

Destroy a space 

DPSDestroySpace 

Destroy a context 

DPSDestroyContext 

1 Items in bold type are operators; all others are Client Library routines. 
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Chapter 4 

Advanced Concepts and Tasks 


In Chapters 2 and 3 you learned the basic concepts and tasks you need to write 
simple applications using XDPS. But to write more complex applications, you 
need the additional concepts and tasks described in this chapter. 


4.1 PostScript Language Encoding 

In XDPS, PostScript language code can be sent to a context in three encodings: 
as a binary object sequence, as binary-encoded tokens, or as ASCII text. Each 
PostScript context has two encoding parameters: DPSProgramEncoding 
and DPSNameEncoding. For an explanation and description of encoding and 
encoding parameters, see the PostScript Language Extensions for the Display 
PostScript System and the Display PostScript System Client Library Reference 
Manual . 

XDPS uses default values for the encoding parameters, so application 
programmers can usually ignore encoding. Table 4-1 shows the default values for 
the encoding parameters. 


Table 4-1: Default PostScript Language Encodings for XDPS 


Context type 

Encoding Parameter 

Default Value 

execution 

DPSProgramEncoding 

Binary object sequence (dps_binOb jSeq) 

execution 

DPSNameEncoding 

User name index (dps indexed) 

text 

DPSProgramEncoding 

ASCII characters (dps_ascii) 

text 

DPSNameEncoding 

User name string (dps string) 


XDPS lets you change the encoding parameters of a context to any of the three 
possible encodings. To change the encoding parameters, use the Client Library 
routine DPSChangeEncoding, described in Chapter 5. 


4.2 Buffering and the Client Library 

In most implementations of the Display PostScript system, the Client Library 
buffers its communications with the Display PostScript server. But in XDPS, the 
Client Library communicates with the server by way of Xlib, which buffers its 
own communication. To avoid duplicate buffering, the XDPS Client Library 
performs no internal buffering. Instead, all buffering of Client Library 
communication occurs in Xlib. As a result, the XDPS Client Library routine 
DPSFlushContext performs the same tasks as the Xlib procedure XFlush. 
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4.3 Accessing Files on the Server 

To preserve security on servers, XDPS lets applications access only certain files 
stored on the server. Specifically, XDPS lets applications access only files stored 
in two directories, referred to here as tempdir and permdir. 

The tempdir directory is temporary: its contents are deleted each time the XDPS 
server is started or reset, such as when the user logs out. In contrast, permdir 
is a permanent directory: resetting and restarting do not affect its contents. 
Applications can both read from tempdir and write to it. Applications can only 
read from permdir ; they cannot write to it. 

To specify a file stored in tempdir , an application must prefix the filename with 
%temp%. To specify a file in permdir , an application must use the prefix %perm%. 
If a filename is preceded by neither %temp% nor %perm%, XDPS searches for the 
file first in tempdir and then in permdir . XDPS does not let applications access 
files whose names include a slash (/), a bracket ([), or a colon(:). 

By default, tempdir is the directory /usr/lib/DPS/tempdir; permdir is 
/usr/lib/DPS/permdir. You can, however, assign other directory names. 

To do so, specify those names in the XDPS server startup command. (For more 
information, see the Release Notes and Installation Instructions .) 


4.4 Converting Coordinates 

The X Window System and the PostScript language use different coordinate 
systems to specify points within the drawing area. As a result, XDPS applications 
sometimes need to convert user space coordinates (used by the PostScript 
language) into X coordinates, and vice versa. (For more information on user 
space, see the PostScript Language Reference Manual.) This section explains how 
to perform these coordinate conversions. 


4,4.1 Preparing to Convert Coordinates 

Before converting coordinates, an application should create a context, and then do 
the following steps: 

1. Perform any user space transformations. 

2. Get the current transformational matrix (CTM), its inverse, and the X 
coordinates of the current user space origin. 

3. Store these values in the VM associated with the context. 

The application can then perform coordinate conversions for the context. 

To get the CTM, its inverse, and the X coordinates of the current user space 
origin, an application can call a custom wrap such as PSWGetTransform, 
whose pswrap source file is shown in Example 4-1. 
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Example 4-1: Wrap Returning CTM, Its Inverse, and Current User Space Origin 


defineps PSWGetTransform(DPSContext ctxt | float ctm[6], invctm[6]; 
int *xOffset, *yOffset) 
matrix currentmatrix dup ctm 
matrix invertmatrix invctm 
currentXoffset exch xOffset yOffset 

endps 


The following C language code calls PSWGet Trans form: 

DPSContext ctxt; 

float ctm[6], invctm[6]; 

int xOffset, yOffset; 

PSWGetTransform(ctxt, ctm, invctm, &xOffset, &yOffset); 


4.4.2 X Coordinates to User Space Coordinates 

To convert an X coordinate into a user space coordinate, an application can 
execute the following C language code: 

#define A_COEFF 0 

#define B_COEFF 1 

#define C_COEFF 2 

#define D_COEFF 3 

#define TX_CONS 4 

#define TY_CONS 5 

int x,y; /* X coordinate */ 

float ux, uy; /* user space coordinate */ 

x -= xOffset; 
y -= yOffset; 

ux = invctm[A_COEFF] * x + invctm[C_COEFF] * y + invctm[TX_CONS]; 
uy = invctm[B_COEFF] * x + invctm[D_COEFF] * y + invctm[TY_CONS]; 


4.4.3 User Space Coordinates to X Coordinates 

To convert a user space coordinate into an X coordinate, an application can 
execute the following C language code: 

x = ctm[A_COEFF] * ux + ctm[C_COEFF] * uy + ctm[TX_CONS] + xOffset; 
y = ctm[B_COEFF] * ux + ctm[D_COEFF] * uy + ctm[TY_CONS] + yOffset; 


4.5 Resizing Windows 

An application or user can resize the window in which XDPS paints. Resizing 
can affect two PostScript language settings, the clipping path and the user space 
origin, as described in the following sections. 
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4.5.1 Window Resizing and the Clipping Path 

PostScript language painting occurs only within the area known as the clipping 
path. When initializing a context, XDPS sets the clipping path equal to the 
size of the window. If the window is resized, however, XDPS does not reset the 
clipping path. Instead, each time the window is resized, the application should 
execute the PostScript language operator initclip, which reinitializes the 
clipping path to match the window's new size. The application can then reexecute 
any code that performs further clipping. 


4.5.2 Window Resizing and the User Space Origin 

When an application resizes the window of a context, the user space origin moves 
according to the bit gravity of the window. Bit gravity is an X window attribute 
that governs how partial window contents are preserved when a window is 
resized. (Bit gravity is not to be confused with window gravity, an X attribute 
that does not affect the user space origin.) In X, specifying the bit gravity of 
a window is optional: the default value is ForgetGravity. XDPS treats 
ForgetGravity as Northwest gravity. 

Because a window’s user space origin moves according to the window’s bit 
gravity, resizing does not change the distance between the user space origin 
and any PostScript language images already displayed. Because this distance is 
unchanged, future PostScript language images align with those already displayed. 

Compare Figures 4-1 and 4-2. The left side of Figure 4-1 shows a window 
displaying the text “NorthWest”. As shown, the user space origin is the window’s 
lower left corner, and the bit gravity is NorthWest. 

The right side of the figure shows the same window after resizing. Notice that 
the user space origin (and hence the displayed text) remains a constant distance 
from the window’s upper left corner: its “NorthWest” corner. 
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Figure 4-1: Resizing Window Whose Bit Gravity Is Northwest 
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In Figure 4-2, the size of the window on the left and the position of its text are 
the same as in Figure 4-1. Also the same is the user space origin: the lower left 
corner. But in Figure 4-2, the bit gravity is Southwest. Therefore, when the 
window is resized, the user space origin and displayed text remain a constant 
distance from the window’s lower left corner: its “SouthWest” corner. 
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Figure 4-2: Resizing Window Whose Bit Gravity Is Southwest 



The user space origin is typically the lower left corner of the drawing space. For 
this reason, typical XDPS applications should explicitly set the bit gravity of their 
windows to Southwest. 


4.6 Synchronizing the Display PostScript System and X 

X imaging calls complete atomically. Therefore, XDPS applications need 
not take special precautions when issuing X imaging calls before PostScript 
language imaging calls. PostScript contexts, however, complete non-atomically 
and asynchronously within the X server. Thus, when an application issues X 
imaging calls immediately after issuing PostScript language calls, the X calls can 
sometimes execute before the PostScript language calls. That is, it is possible for 
X and the Display PostScript system to become unsynchronized. 

Few applications need to synchronize the Display PostScript system and X 
explicitly. But to do so, an application can call the Client Library routine 
DPSWaitContext before issuing the X imaging calls that follow PostScript 
language calls. DPSWaitContext forces the PostScript language calls to 
complete before the X calls. 


NOTE 

DPSWaitContext causes a round trip to the server. Such trips 
impair performance, so call DPSWaitContext only when needed. 

For more information on DPSWaitContext, see the Display PostScript System 
Client Library Reference Manual . 
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4.7 Synchronizing Client and Context 

Applications, or clients, sometimes need to pause the execution of a context. 
Pausing a context lets an application take control when the PostScript interpreter 
reaches certain points within a PostScript language procedure. 

To pause a context, an application sends the system-specific PostScript language 
operator clientsync. The clientsync operator causes a context to enter 
the FROZEN state. The context remains in that state until the application calls 
the Client Library routine XDPSUnfreezeContext. For more information 
on clientsync, see its description in Chapter 6. For a description of 
XDPSUnf reezeContext, see Chapter 5. 


4.8 Sharing Contexts and Spaces 

Although the XDPS Client Library lets applications share contexts and spaces, 
it does not coordinate the sharing. Instead, the applications themselves must 
coordinate any sharing of resources. 

The sharing applications must avoid race conditions and deadlocks. In addition, if 
one application obtains the XID of a resource created by another, the application 
that obtained the XID must create records and handles to access the shared 
resource through the Client Library. 

A context or space cannot be destroyed while shared. If such a resource is shared, 
the routines DPSDestroyContext and DPSDestroySpace destroy the client 
data structures created to access the shared resource but do not destroy the 
resource itself. After a resource is no longer shared, an application can destroy it 
by calling DPSDestroyContext or DPSDestroySpace. 


4.9 Using Color 

In XDPS, the Display PostScript system paints colors and gray shades on an X 
server. An X server can render only a finite number of exact colors and shades 
simultaneously; it represents each as a pixel value. (For more information, see 
the Guide to the Xlih Library: C Language Binding.) In contrast, the PostScript 
language represents colors and shades not as pixel values but as “pure” colors 
and “pure” shades, without regard for whether the output device can render them 
exactly. As a result, to paint on an X display, a PostScript context must first find 
whether there is a pixel value that matches the pure color or shade specified by 
the PostScript language. 


4.9.1 Converting Colors and Shades into Pixel Values 

To find the pixel value that matches a particular color or shade, a context 
searches the color cube or gray ramp. The color cube and gray ramp specify 
pixel values that correspond to a subset of all possible pure colors and shades. 
(For more information, see colormap and XStandardColormap in the Guide to 
the Xlib Library: C Language Binding.) 

The color cube defines a set of colormap cells whose values form a series of color 
ramps (progressive changes in color). Each axis of the color cube represents one 
of three hues: red, green, or blue (r/g/b); all displayed colors are composites of 
these hues. Values along the axes of the cube represent intensity of hue and 
increase from 0% to 100% of the displayed color. Note that the color cube is not 
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a cube in the strict sense of the word: the axes need not have the same “length,” 
that is, the same number of values. 

The gray ramp defines a set of colormap cells whose values form a single 
color ramp of gray shades. Values along the gray ramp represent comparative 
intensities of black and white. Along the ramp, the intensity of white increases 
from 0% to 100%. 

If the color cube or gray ramp contains a pixel value that exactly matches 
the specified pure color or shade, the context uses the pixel value to paint the 
pure color or shade. Otherwise, the context approximates the color or shade by 
dithering, by painting a pattern of colors or gray shades from its color cube or 
gray ramp. 


4.9.2 Defining a Color Cube and Gray Ramp 

When creating a context, an application must allocate and define a color cube and 
gray ramp. If the application defines no color cube, the context renders colors by 
dithering from the gray ramp. If the application defines neither a color cube nor 
a gray ramp, the context cannot paint. 

Typically, applications create contexts by calling XDPSCreateSimpleContext. 
This routine allocates and defines a color cube and gray ramp using the 
XStandardColormap structures RGB_DEFAULT__MAP and RGB_GRAY__MAP. If 
these structures do not exist, XDPSCreateSimpleContext allocates them. To 
allocate and define a different color cube and gray ramp, an application can use 
either of two methods: 

• Create the context by calling XDPSCreateContext. 

• Create the context by calling either XDPSCreateSimpleContext 
or XDPSCreateContext; and then use the X-specific operator 
setXgcdrawablecolor to redefine the color cube and gray ramp. 

To allocate and define a color cube and gray ramp, an application performs the 
following steps: 

1. Calls XCreateColormap to create a colormap. (This optional step is needed 
only if the application does not use the default colormap.) 

2. Calls XAllocColorCells to allocate the colormap cells needed to store the 
color cube and gray ramp. 

3. Calls XStoreColors to store a color for each pixel value in the color cube 
and gray ramp. 

4. Calls XDPSCreateContext to create a context and pass the 
XStandardColormap structures describing the color cube and gray ramp. 

The rest of this section describes how XDPS uses the color cube and gray ramp. 
The section refers to the elements of the color cube and gray ramp by the 
following names: 

maxred 

redmult 

maxgreen 

greenmult 

maxblue 

bluemult 

firstcolor 

maxgrays 
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graymult 

firstgray 

colormapid 


These names are the same as those used for elements of the colorinf o array, 
which is accessed by the X-specific operators setXgcdrawablecolor and 
currentXgcdrawablecolor. (For more information, see the description of 
these operators in Chapter 6.) 


4.9.2.1 Using the Color Cube 

To render an exact color, XDPS searches the colormap for the pixel value 
matching the r/g/b value specified in the color cube. Conceptually, the color cube 
is three-dimensional; the colormap, however, is conceptually one-dimensional. 
Thus, to find the pixel value that matches an r/g/b value, XDPS uses the following 
formula: 


PixelValue = r * redmult + g * greenmult 4- b * bluemult + firstcolor 

In this formula, r, 6, and g are integers. The integer r is in the range [0, maxred ]; 
g is in the range [0, maxgreen ]; and b is in the range [0, maxblue ]. 

A color cube must start at pixel firstcolor in the X colormap colormapid. 
Along the red, green, and blue axes of the cube, values should increase from zero 
to the maximum values for each axis. For example, one common color allocation 
is 3/3/2 (three reds, three greens, and two blues). This allocation results in the 
following maximum value for each hue: 

maxred = 2 
maxgreen = 2 
maxblue = 1 

In the colorinfo array, the elements redmult , greenmult , and bluemult are the 
scale factors that determine the spacing of the cube in the linear colormap. For 
the 3/3/2 color cube mentioned earlier, appropriate values might be: 

redmult = 32 
greenmult = 4 
bluemult = 1 


NOTE 

In an empty color cube, maxred , maxgreen , and maxblue each equal -1, 
not zero. 


4.9.2.2 Using the Gray Ramp 

The gray ramp must start at pixel firstgray in XStandardColormap 
colormapid. To find the pixel value that matches a gray value, XDPS uses 
the following formula, where gray is an integer in the range [0, maxgrays}: 

PixelV alue = gray * graymult + firstgray 

For example, suppose you want to define a 5-cell gray ramp whose values increase 
from 0% to 100% in steps of 20%. If the corresponding five colormap entries are 
contiguous, you can describe the map by setting maxgray to 4 and graymult to 1. 

A gray ramp must consist of at least two cells: one for black, one for white. If 
the colormap is associated with the default visual type, you can use the following 
values to form a 2-cell gray ramp consisting of BlackPixel and WhitePixel: 
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maxgrays = 1 

graymult = WhitePixel — BlackPixel 
firstgray ~ BlackPixel 


4.9.3 Rendering Colors Not in the Color Cube 

By default, XDPS dithers to render any color not in the color cube. To render such 
an additional color exactly, an application must cause the X server to allocate a 
colormap cell for the additional color. 

To control whether additional colors are rendered exactly or by dithering, an 
application can set the actual element of the colorinfo array. The actual 
element specifies the maximum number of additional colormap cells that the 
server attempts to allocate. Thus, it limits the number of additional colors that 
the server attempts to render exactly. 

If actual is nonzero, the server attempts to allocate a colormap cell for each 
additional color until it has allocated actual cells. After actual cells have been 
allocated, the server renders any future additional colors by dithering. If actual 
equals zero, the server dithers to render all colors not found in the color cube. 

To override the maximum set by actual, an application can use the X-specific 
operator setrgbXactual. 


CAUTION 

XDPS does not limit the number of colormap cells that one context or 
one application can allocate. 


4.9.4 The colorinfo Array and XStandardColormap Structures 

The color cube and gray ramp are passed to XDPSCreateContext as 
XStandardColormap structures. Tables 4-2 and 4-3 show how the entries 
in these XStandardColormap structures correspond to elements in the 
colorinfo array. 


Table 4-2: Mapping Between colorinfo Array and XStandardColormap Storing 
Color Cube 


colorinfo Element 

XStandardColormap Element 

maxred 

red max 

redmult 

red mult 

maxgreen 

green max 

greenmult 

green mult 

maxblue 

blue max 

bluemult 

blue mult 

firstcolor 

base pixel 
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Table 4-3: Mapping Between colorinfo Array and XStandardColormap Storing 


Gray Ramp 


colorinfo Element 

XStandardColormap Element 

maxgrays 

red_max 

graymult 

red_mult 

firstgray 

base pixel 

colormapid 

colormap 
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Chapter 5 

Client Library Routines for UWS 


The Client Library is the set of C language routines by which XDPS applications 
access a server, that is, the PostScript interpreter of an X server. The Client 
Library includes routines that create, communicate with, and destroy PostScript 
contexts on the server. 

Most Client Library routines are common to all windowing systems that 
implement the Display PostScript system. But for any particular windowing 
system, such as X, additional routines and data structures must be added to the 
Client Library. 

This chapter describes UWS-specific routines and data structures that have 
been added to the Client Library. For descriptions of system-independent Client 
Library routines, see the Display PostScript System Client Library Reference 
Manual . In addition, see that book for information on system-independent Client 
Library concepts and tasks. 

For the rest of this chapter, except where noted, the term “Client Library” refers 
to the Display PostScript system Client Library as implemented in UWS. 

The Client Library routines are defined in six C-language header files: 

• dpsclient.h 

• dpsfriends.h 

• dpsexcept.h 

• dpsops.h 

• psops.h 

• dpsXclient.h 

The first five of these files are common to all implementations of the Display 
PostScript system and are described in the Display PostScript System Client 
Library Reference Manual . The sixth file, dpsXclient .h, is specific to XDPS 
and is described in the following section. 


5.1 System-Specific Header File 

The header file dpsXclient.h defines the system-specific Client Library 
routines and data structures of XDPS. Like the other Display PostScript system 
header files, dpsXclient .h is located in the directory /usr/include/DPS. 
The dpsXclient. h file is the only Client Library header file that all XDPS 
applications must include. 
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5.2 X-Specific Singleops 

The Client Library includes a set of routines called singleops (single-operator 
wrapped procedures). Each singleop sends one or more operators to a context. 

For instance, the singelop PSshowpage sends the operator showpage. 

For each operator, the Client Library defines two singleops: one takes an implicit 
context argument (always the current context); the other takes an explicit context 
argument. For example, the Client Library contains the singleops PSshowpage 
and DPS showpage. Although both singleops execute the operator showpage, 
PSshowpage takes an implicit context argument; DPS showpage takes an 
explicit one. 

Implicit-context singleops are defined in the header file psops .h; explicit-context 
singleops are defined in dpsops . h. If your application creates only one context, 
using implicit-context singleops can make coding easier. 

The Client Library includes X-specific singleops. Each of these singleops sends 
an X-specific operator, for example, setXgcdrawable. Like other singleops, 
X-specific singleops are of two types: implicit-context and explicit-context. 
X-specific singleops that take an implicit context argument are defined in the 
file pscustomops . h, which is included by psops . h. X-specific singleops that 
take an explicit context are defined in dpscustomops .h, which is included by 
dpsops. h. 

Example 5-1 shows the definitions of the X-specific singleops. Table 5-1 describes 
the arguments used in the definitions. For descriptions of the operators that the 
X-specific singleops send, see Chapter 6. For general information about singleops, 
see the Display PostScript System Client Library Reference Manual . 

Example 5-1: Definitions of X-specific Singleops 


extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 
extern void 


DPSclientsync( /* DPSContext ctxt; */ ); 

DPScurrentXgcdrawable{ /* DPSContext ctxt; int *gc, *d, *x, *y; */ ); 
DPScurrentXgcdrawablecolor( /* DPSContext ctxt; int *gc, *d, *x, *y, colorlnfo[12]; 
DPScurrentXoffset( /* DPSContext ctxt; int *xOffset, *yOffset; */ ); 
DPSsetXgcdrawable( /* DPSContext ctxt; int gc, d, x, y; */ ); 

DPSsetXgcdrawablecolor( /* DPSContext ctxt; int gc, d, x, y, colorlnfo[12]; */ ); 
DPSsetXoffset( /* DPSContext ctxt; short int x, y; */ ); 

DPSsetXrgbactual( /* DPSContext ctxt; int r, g, b; Boolean ^success; */ ); 
PSclientsync(); 

PScurrentXgcdrawable{ /* int *gc, *d, *x, *y; */ ); 

PScurrentXgcdrawablecolor( /* int *gc, *d, *x, *y, colorlnfo[12]; */ ); 

PScurrentXoffset( /* int *xOffset, *yOffset; */ ); 

PSsetXgcdrawable( /* int gc, d, x, y; */ ); 

PSsetXgcdrawablecolor( /* int gc, d, x, y, colorlnfo[12]; */ ); 

PSsetXoffset ( /* int x, y; */ ); 

PSsetXrgbactual( /* int r, g, b; Boolean *success; */ ); 


*/ ) 
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Table 5-1: Arguments Used by X-Specific Singleops 


Name 

Type 

Description 

colorInfo[12] 

integer 

array 

Stores color attributes of the context. The 
elements of this array are graymax, 
graymult, firstgray, redmax, redmult, 
greenmax, greenmult, bluemax, bluemult, 
firstcolor, colormapid, and numactual. 

d 

integer 

The X resource ID of an X drawable. If d equals 
zero, all drawing operations are ignored. 

gc 

integer 

The GContext resource ID for the X 

Graphic Context of drawable. If gc equals 
zero, all drawing operations are ignored. To 
obtain a value for gc , call the Xlib routine 
XGContextFromGC ( ), passing the Xlib data 
type GC of the current X Graphic Context as the 
argument. 

r, g, b 

integer 

Levels for red, green, and blue, in the X color 
space [0..65535]. 

success 

Boolean 

When nonzero, shows that the singleop completed 
without a PostScript language error. When zero, 
shows that the singleop produced a PostScript 
language error on the server. 

x andy 

integer 

The horizontal and vertical coordinates (in X 
units) for the default user space origin of the 
current drawable. If x equals zero, and y equals 
the height of the drawable (in pixels), the default 
user space origin is at the lower left comer of the 
drawable. In the PostScript language, this is the 
typical location for the default user space origin. 

xOffset and 
yOffset 

integer 

Same as x y; see descriptions in this table. 


5.3 Naming Conventions 

Table 5-2 shows conventions used to name the UWS-specific Client Library 
routines. 


Table 5-2: Naming Conventions in the Client Library 


Type of Routine 

Naming Convention 

System-specific Routine 

jyPSMnemonic_name 

(continued on next page) 
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Table 5-2 (Cont.): Naming Conventions in the Client Library 


Type of Routine 

Naming Convention 

X-specific Client Library routine 

Singleop with implicit context argument 

Singleop with explicit context argument 

XDPSMnemonic_name 

T?Soperator_name 

TfPSoperatorjiame 



5.4 Format of Routine Descriptions 


The rest of this chapter describes each system-specific Client Library routine and 
data structure. Each description follows this format: 

NameOfRoutine 

/* C-language definition of the routine 7; 

Text describing what the routines does and what its 
arguments represent. 


5.5 Client Library Routine Descriptions 


This section lists and describes the system-specific Client Library routines. 
The descriptions are arranged alphabetically by name. The format of these 
descriptions is explained in Section 5.4. 

Following is a list of the system-specific routines and data structures: 


DPSChangeEncoding 

DPSContextFromContextID 

DPSCreateTextContext 

DPSDefaultTextBackstop 

DPSNewUserObjectIndex 

XDPSContextFromSharedID 

XDPSContextFromXID 

XDPSCreateContext 

XDPSCreateSimpleContext 

XDPSFindContext 

XDPSRegisterStatusProc 

XDPSSetStatusMask 

XDPSSpaceFromSharedID 

XDPSSpaceFromXID 

XDPSUnfreezeContext 

XDPSXIDFromContext 

XDPSXIDFromSpace 


The rest of this chapter describes the items listed. 
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DPSChangeEncoding 

void DPSChangeEncoding 
(/* DPSContext ctxt; 

DPSProgramEncoding newProgEncoding; 
DPSNameEncoding newNameEncoding 7); 
DPSChangeEncoding sets the value of one or both 
encoding parameters of the context specified by ctxt. If the 
encoding parameters are set to values other than the default 
values, DPSWritePostScript, singleops, and custom 
wraps convert PostScript language code to the specified 
encoding before sending it to context ctxt. 

For a list of the default encodings, see Section 4.1. 


DPSContextFromContextID 

DPSContext 

DPSContextFromContextlD(/* 

DPSContext ctxt; 
long int cid; 

DPSTextProc textProc; 

DPSErrorProc errorProc */); 

DPSContextFromContextID returns the DPSContext 
handle of the context whose PostScript language ID is cid. 
Context cid is one created when a preexistent context, ctxt , 
executed the PostScript operator fork. The arguments 
textProc and errorProc specify the two routines with which 
the calling client handles text and errors from the context 
cid. 

If the calling client has no context record for context cid , 
DPSContextFromContextID creates one. The new 
context record uses the text handler and error handler 
passed in textProc and errorProc. If textProc or errorProc is 
NULL, the new context record uses the text handler and error 
handler of ctxt. 

Except for the text handler, error handler, and chaining 
pointers, the created context record inherits all its 
characteristics from ctxt. (For an explanation of chained 
contexts, see the Display PostScript System Client Library 
Reference Manual.) 


Client Library Routines for UWS 5-5 



DPSCreateTextContext 

DPSContext 

DPSCreateTextContext(/* 

DPSTextProc textProc; 

DPSErrorProc errorProc */); 

DPSCreateTextContext creates a context record and 
DPSContext handle not associated with an execution 
context. When this DPSContext handle is passed as the 
argument to a Client Library routine, that routine converts 
all context input into ASCII text, and then passes that text 
to the text-handling routine textProc. The routine specified 
by errorProc handles errors that result from improper context 
usage. (For example, one such error occurs if the context is 
invalid.) 

Do not use the errorProc routine to handle errors that result 
from executing textProc. For example, if your textProc routine 
writes text to a file, do not use errorProc to handle file-related 
errors, such as those that occur when a file is write-protected. 
(For more information, see the Display PostScript System 
Client Library Reference Manual.) 


DPSDefauItTextBackstop 

void DPSDefauItTextBackstop 
(/* DPSContext ctxt; 
char *buf; 
unsigned count 7); 

DPSDefauItTextBackstop is a text-handling routine; 
it is the default text backstop installed by the Client 
Library. Because DPSDefauItTextBackstop is 
of type DPSTextProc, it can be specified as the 
text-handling routine {textProc) in context-creation 
routines, such as XDPSCreateSimpleContext. 
DPSDefauItTextBackstop writes text to ULTRIX 
stdout and flushes stdout. 


DPSNewUserObjectlndex 

long int DPSNewllserObjectlndex(); 

DPSNewUserObjectlndex returns a new user object 
index. All new user object indices are allocated by the Client 
Library. 

User object indices are dynamic; do not compute with them or 
store them in long-term storage, such as in a file. For more 
information about user object indices, see the PostScript 
Language Extensions for the Display PostScript System. 
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XDPSContextFromSharedID 

DPSContext 

XDPSContextFromSharedlD(/* 

Display *dpy; 

PSContextID cid; 

DPSTextProc textProc; 

DPSErrorProc errorProc 7); 

XDPSContextFromSharedID returns the DPSContext 
handle of an existing context, specified by PostScript 
language ID (cid) and X display (dpy). If the calling client 
has no such DPSContext, XDPSContextFromSharedID 
creates a DPSContext and the associated 
DPSContextRec. 

The arguments textProc and errorProc specify the two 
routines with which the calling client handles text and 
errors from the specified context. 

XDPSContextFromSharedID lets one client access a 
context created by another client, thereby letting multiple 
clients share a single context. When sending names to 
shared contexts, XDPSContextFromSharedID uses name 
string encoding. 


XDPSContextFromXID 

DPSContext 

XDPSContextFromXlD(/* 

Display *dpy; 

XID xid 7); 

XDPSContextFromXID returns the DPSContext handle 
of an existing context, specified by X resource ID (xid) and X 
display (dpy). 
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XDPSCreateContext 


DPSContext 

XDPSCreateContext(/* 

Display *dpy; 

Drawable drawable; 

GC gc; 

int x,y; 

unsigned int eventmask; 

XStandardColormap *grayramp; 

XStandardColormap *ccube; 

int actual; 

DPSTextProc textProc; 

DPSErrorProc errorProc; 

DPSSpace space 7); 

XDPSCreateContext creates an execution context and the 
associated DPSContextRec data structure. It returns a 
DPSContext handle. 

Unlike XDPSCreateSimpleContext, 
XDPSCreateContext lets you explicitly specify all 
characteristics of the context, including its colormap 
entries. But, unless your application uses color in an 
unusual way, you need not use XDPSCreateContext; 
use XDPSCreateSimpleContext instead. 

When called, XDPSCreateContext checks whether the X 
server dpy supports a Display PostScript system extension. 

If not, the routine returns NULL; if so it checks that the 
specified drawable and GC exist on the same screen. If they 
do not, the X server returns a BadMatch error. If they do, 
XDPSCreateContext creates a PostScript context having 
the characteristics specified in the arguments passed. 

If the argument drawable or GC is NULL, the created 
context can receive and execute PostScript language input, 
but cannot paint images until the calling application 
specifies an X drawable and GC. (To specify these values, 
the application must send an X-specific operator, such as 
setXgcdrawable, described in Chapter 6.) 

The following table describes the arguments of 
XDPSCreateContext. 


Argument 

Name 

Description 

dpy 

An X display. 

drawable 

An X drawable on display. 

GC 

The X Graphic Context associated with 
drawable. 

x andy 

The horizontal and vertical coordinates (in 
X units) for the default user space origin of 
drawable. If x equals zero and y equals the 
height of drawable (in pixels), the default 
user space origin is at the lower left comer 
of drawable. In the PostScript language, 
this is the typical location for the default 


user space origin. 
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Argument 

Name Description 


eventmask 

grayramp 

ccube 

and 

grayramp 


actual 


textProc 

errorProc 

space 


Ignored; reserved for future use. Use zero 
as the value of this argument. 

(See ccube.) 

ccube identifies a set of color cells defined as 
a series of color ramps; grayramp identifies 
a set of color cells defined as a gray ramp. 
The context uses ccube smdgrayramp to 
produce actual colors and dithered colors. 

If ccube equals NULL, colors are rendered 
in shades of gray only. If grayramp equals 
NULL, the context does not paint. The gray 
ramp must have at least two elements: one 
for black and one for white. 

The X client must allocate and define 
ccube and grayramp and must install the 
associated colormap. In general, if the 
client specifies a plane mask, ccube and 
grayramp should be within the planes 
selected by the plane mask, to ensure that 
the Display PostScript system interacts 
properly with the plane mask. 

For more information, see Section 4.9. 

Specifies whether the application prefers 
to paint with actual (not dithered) colors 
and, if so, specifies how many actual colors 
it needs. The actual argument is a hint 
to the X server: dithering and actual color 
allotment are governed by the X server, not 
by the application. 

If actual equals zero, the application paints 
by dithering colors from grayramp and 
ccube. If actual is not zero, the application 
paints using a maximum of actual actual 
colors; all additional colors are dithered. 

The routine that this context calls to handle 
text output. 

The routine that this context calls if it 
encounters an error condition. 

The private VM in which this context 
executes. If space is NULL, a new space 
is created for the context; otherwise, the 
context shares the specified space. 
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XDPSCreateSimpleContext 

DPSContext 

XDPSCreateSimpleContext(/* 

Display *dpy; 

Drawable drawable; 

GC gc; 
int x,y; 

DPSTextProc textProc; 

DPSErrorProc errorProc; 

DPSSpace space 7); 

XDPSCreateSimpleContext creates an execution context 
and the associated DPSContextRec data structure. It 
returns a DPSContext handle. 

When called, XDPSCreateSimpleContext checks 
whether the X server dpy supports a Display PostScript 
system extension. If not, the routine returns NULL; if so, it 
checks that the specified drawable and GC exist on the same 
screen. If they do not, the X server returns a BadMatch 
error. If they do, XDPSCreateSimpleContext creates a 
PostScript context having the characteristics specified in the 
arguments passed. 

If the argument drawable or GC is NULL, the created 
context can receive and execute PostScript language input, 
but cannot paint images until the calling application 
specifies an X drawable and GC. (To specify these values, 
the application must send an X-specific operator, such as 
setXgcdrawable, described in Chapter 6.) 

The following table describes the arguments of 
XDPSCreateSimpleContext. 


Argument 

Name 

Description 

dpy 

An X display. 

drawable 

An X drawable on display. 

GC 

The X Graphic Context associated with 
drawable . 

x and y 

The horizontal and vertical coordinates (in 
X units) for the default user space origin 
of drawable . If x equals zero and y equals 
the height of drawable , the default user 
space origin is at the lower left comer of 
drawable. In the PostScript language, this 
is the typical location for the default user 
space origin. 

textProc 

The routine that this context calls to handle 
text output. 

errorProc 

The routine that this context calls if it 
encounters an error condition. 

space 

The private VM in which this context 
executes. If space is NULL, a new space 
is created for the context; otherwise, the 
context shares the specified space . 
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Unlike the XDPSCreateContext routine, 
XDPSCreateSimpleContext does not let you explicitly 
specify the colormap of the created context, nor does it let you 
set characteristics of the colormap. Instead, the routine uses 
standard colormaps as described in the following paragraph. 
XDPSCreateSimpleContext accesses the X server 
dpy and finds out whether the standard colormaps 
RGB_DEFAULT_MAP and RGB_GRAY_MAP are defined. 

If they are defined, XDPSCreateSimpleContext uses 
them; otherwise, the routine defines them. 

After these values are defined, any context 
that the application creates by calling 
XDPSCreateSimpleContext uses RGB_DEFAULT_MAP 
and RGB_GRAY__MAP. Note, however, that contexts created 
by calling XDPSCreateContext use the color cube and 
gray ramp specified in the call to that routine. 

For more information about XDPSCreateSimpleContext, 
see the Display PostScript System Client Library Reference 
Manual. For information on explicitly specifying the color 
characteristics of a context, see the description of 
XDPSCreateContext in this chapter. 


XDPSFindContext 

DPSContext 

XDPSFindContext(/* 

Display *dpy; 
long int cid 7); 

XDPSFindContext returns the DPSContext handle of 
the context whose ID is specified in cid. 

The argument cid is the result returned by an operator such 
as current context; dpy specifies the X display where the 
context is running. 
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XDPSRegisterStatusProc 

typedef void (*XDPSStatusProc)(/* 
DPSContext ctxt; 
int code */); 


void 

XDPSRegisterStatusProc (/* 

DPSContext ctxt; 

XDPSStatusProc proc 7); 

XDPSRegisterStatusProc specifies the routine 
that an application calls to handle status events 
(XDPSStatusEvent) from the context ctxt. That is, 
XDPSRegisterStatusProc registers, or associates, 
the XDPSStatusProc event-handling routine proc with the 
context ctxt. 

The routine proc has two arguments: ctxt and code . The 
argument ctxt specifies the context with which proc is 
registered; code shows the status code of the event for which 
proc was called. The client can call proc at any time to 
process status events. 

If an XDPSStatusProc routine is already registered with 
the context ctxt , XDPSRegisterStatusProc supersedes 
the existing registration with the value of proc. 
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XDPSSetStatusMask 

void 

XDPSSetStatusMask(/* 

DPSContext ctxt; 
unsigned long enableMask; 
unsigned long disableMask; 
unsigned long nextMask 7); 

XDPSSetStatusMask sets the context status mask 
of the context specified in the argument ctxt . (For a 
explanation of context status and the context status mask, 
see Section 2.2.3.) 

The argument enableMask specifies which kinds of context 
status events the XDPS server sends to the calling 
application; disableMask specifies the kinds of context status 
events the server does not send. The argument nextMask 
causes the server to send only the next instance of each 
specified kind of context status event. The enableMask , 
disableMask , and nextMask arguments each represent one or 
more of the values listed in the following code extract: 

#define PSRUNNINGMASK 0x0001 

tdefine PSNEEDSINPUTMASK 0x0002 

Idefine PSZOMBIEMASK 0x0004 

#define PSFROZENMASK 0x0008 

To assign more than one value to a single argument, perform 
a bitwise inclusive OR operation ( I ) on the values you wish 
to assign, as in the following example. 

XDPSSetStatusMask(PSRUNNINGMASK | PSNEEDSINPUTMASK,0,0); 


The following table describes the valid values for enableMask , 
disableMask , and nextMask . 


Mask value 

Status Events Affected 

PSFROZENMASK 

Events that show the 
context is frozen 

P SNEED SINPUTMASK 

Events that show the 
context needs input 

PSRUNNINGMASK 

Events that show the 
context is in the runnable 
state. 

PSZOMBIEMASK 

Events that show the 
context is in the zombie 
state. 


Note that, if an application sends input to a context that is 
in the zombie state, the application receives a zombie status 
event, regardless of how the status mask is set. 
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XDPSSpaceFromSharedID 

DPSSpace 

XDPSSpaceFromSharedlD(/* 

Display *dpy; 

SpaceXID sid 7); 

XDPSSpaceFromSharedID returns the DPSSpace handle 
of an existing private context space, specified by X resource 
ID (sid) and display (dpy). If the calling client has no 
such DPSSpace, XDPSSpaceFromSharedID creates the 
DPSSpace and associated DPSSpaceRec data structure. 
XDPSSpaceFromSharedID lets a context created by one X 
client share the private space of a context created by another 
X client. When sending names to shared context whose 
private space is shared, XDPSSpaceFromSharedID uses 
ASCII encoding. 


XDPSSpaceFromXID 

DPSSpace 

XDPSSpaceFromXID(/* 

Display *dpy; 

XID xid 7); 

XDPSSpaceFromXID returns the DPSSpace pointer of an 
existing private context space, specified by X resource ID 
(sid) and display (dpy). 


XDPSUnfreezeContext 

void 

XDPSUnfreezeContext (/* 

DPSContext ctxt 7); 

XDPSUnfreezeContext causes the specified frozen 
context to resume executing. The argument ctxt is the ID 
of a context whose status is PSFROZEN. 


XDPSXIDFromContext 

XID 

XDPSXI DFromContext(/* 

Display **Pdpy; 

DPSContext ctxt 7); 

XDPSXIDFromContext returns the X resource ID of the 
context whose DPSContext handle is ctxt. In addition, the 
routine returns the argument Pdpy, which points to the X 
Display structure associated with ctxt. 
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XDPSXIDFromSpace 

XID 

XDPSXIDFromSpace(/* 

Display **Pdpy; 

DPSSpace spc */); 

XDPSXIDFromSpace returns the X resource ID of the 
context associated with the DPSSpace pointer spc. In 
addition, the routine returns the argument Pdpy, which 
points to the X Display structure associated with spc. 
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Chapter 6 

X-Specific Operators for UWS 


The Display PostScript system extends the PostScript language to include 
operators for generic window-related tasks; but, for tasks that relate specifically 
to X, the window system of UWS, additional operators are needed. To fill this 
need, UWS extends the PostScript language to include X-specific operators. 

This chapter describes the X-specific operators for UWS. For descriptions of 
extensions to the PostScript language, see the PostScript Language Extensions 
for the Display PostScript System and the PostScript Language Color Extensions. 
For a description of the basic PostScript language, see the PostScript Language 
Reference Manual. For general information about window system support in the 
Display PostScript system, see that topic in the Display PostScript System Client 
Library Reference Manual . 

The Client Library defines single-operator procedures that execute the X-specific 
operators. For information on these procedures, see Chapter 5. 


6.1 About the Operators 

The operators described in the rest of this chapter are arranged alphabetically by 
operator name. Each description follows this format: 


operator 

operand -j ... operand n operator result 1 ... result m 

Text describing what the operator does. 

EXAMPLE: 

Sample PostScript language code showing how to use 
the operator. (Optional.) 

ERRORS: 

A list of the errors this operator might execute 


Each operator description begins with a syntax summary. In it, operandi through 
operand n are the operands that the operator requires; operandi is the top 
element on the operand stack. A dash (—) in the operand position means the 
operator accepts no operands. 

The operator pops the operands from the stack and processes them. After 
executing, the operator pushes result\ through result m on the stack; result m is 
the top element. A dash (—) in the result position means the operator returns 
no results. 
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Table 6-1 describes the values used as operands and results by the X-specific 
operators for UWS. All operands are required. 


Table 6-1: Operands and Results for X-Specific Operators 


Name 

Type 

Description 

colorinfo 

integer 

array 

Stores color attributes of the context. The 12 
elements of colorinfo are graymax, graymult, 
firstgray, redmax, redmult, greenmax, 
greenmult, bluemax, bluemult, firstcolor, 
colormapid, and numactual. (For more 
information, see Section 4.9.4.) 

drawable 

integer 

The X window ID or pixmap ID of an X drawable. 

If drawable equals zero, all drawing operations are 
ignored. 

gc 

integer 

The GContext resource ID for the X Graphic 
Context of drawable . If gc equals zero, all drawing 
operations are ignored. To obtain a value for gc, call 
the Xlib routine XGContextFromGC, passing the 
Xlib data type GC of the current Graphic Context as 
the argument. 

red green 
and blue 

float 

Three real numbers in the range 0.0 to 1.0 
that, together, specify a color (as in the operator 

setrgbcolor). 

success 

integer 

When nonzero, indicates that the operator completed 
without error. 

x andy 

integer 

The horizontal and vertical coordinates (in X units) 
for the default user space origin of the current 
drawable. If x equals zero and y equals the height of 
the drawable, the default user space origin is at the 
lower left corner of the drawable. In the PostScript 
language, this is the typical location for the default 
origin. 


Note that drawable, gc, x, and y are part of the PostScript graphics state, which 
can be saved and restored using the PostScript language operators gsave and 
grestore. 


6.2 Operator Errors 

Table 6-2 shows the errors that the X-specific operators can return. 


Table 6-2: Errors for X-Specific Operators 


Error 

Probable Cause 

rangecheck 

Bad match: the drawable and GC do not have the same 
depth, or their visual does not match the colormap 
associated with the context. 

stackunderflow 

Too few operands on the operand stack. 

typecheck 

Invalid ID for drawable or for GC. 


(continued on next page) 
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Table 6-2 (Cont.): 

Errors for X-Specific Operators 

Error 

Probable Cause 

undefined 

Context not associated with a display device. 


6.3 Operator Descriptions 

Following is an alphabetical list and description of the X-specific operators for 
UWS. The format for these descriptions is explained in Section 6.1. 


clientsync — clientsync — 

The clientsync operator pauses the current context, 
sets the status of the context to FROZEN, and causes 
the X server to return a PS FRO ZEN status event. The 
context stays frozen until the application calls the Client 
Library routine XDPSUnf reezeContext ( ) . Thus, 
clientsync synchronizes the application with the 
current context. 

One possible use of clientsync is to display PostScript 
language output one page at a time by pausing the 
current context after each page, as in the following 
example. This example redefines the operator showpage, 
so that the operator first pauses the current context. 

EXAMPLE: 

/showpage { 
clientsync 
showpage 
} bind def 

ERRORS: 

None 


currentXgcdrawable 

— currentXgcdrawable gc drawable x y 

The currentXgcdrawable operator returns the X 
Graphic Context, drawable, and default user space origin 
of the current context. 

Note that the results returned by 
currentXgcdrawable can be used as the operands 
of setXgcdrawable. 

ERRORS: 

undefined 
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currentXgcdrawablecolor 


currentXoffset 


setrgbXactual 


setXgcdrawable 


— currentXgcdrawablecolor gc drawable x y colorinfo 


The currentXgcdrawablecolor operator returns 
the GC, drawable, default user space origin, and color 
attributes of the current context. 

Note that the results returned by 
currentXgcdrawablecolor can be used as the 
operands of setXgcdrawablecolor. 

ERRORS: 

undefined 


— currentXoffset x y 

The currentXoffset operator returns the default 
user space origin of the current context. 

Note that the results returned by currentXoffset can 
be used as the operands of setXoffset. 

ERRORS: 

undefined 


red green blue setrgbXactual success 

The setrgbXactual operator allocates a new colormap 
entry to display the color specified by red, green, blue. 

If the allocation succeeds (if success is nonzero), future 
painting of this color uses the new colormap entry instead 
of dithering from the colorcube. 

Note that setrgbXactual does not affect the graphics 
state. Thus, to paint with the specified color, you must 
first execute the operator setrgbcolor. 

ERRORS: 

stackunderflow undefined typecheck 

gc drawable x y setXgcdrawable — 

The setXgcdrawable operator sets the X Graphic 
Context, drawable, and default user space origin of 
the current context. The values supplied as operands 
supersede any existing values for these attributes. 

The setXgcdrawable operator causes all subsequent 
operations of the current context to occur in the specified 
X drawable, with the specified Graphic Context and 
default user space origin. 

To make the effects of setXgcdrawable temporary, use 
it between the operators gsave and grestore. 
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ERRORS: 

rangecheck stackunderflow typecheck undefined 


setXgcdrawablecolor 


setXoffset 


gc drawable x y colorinfo setXgcdrawablecolor — 

The setXgcdrawablecolor operator sets the GC, 
drawable, default user space origin, and color attributes of 
the current context. 

ERRORS: 

rangecheck stackunderflow typecheck undefined 
x y setXoffset — 

The setXoffset operator sets the default user space 
origin for the current context. 

ERRORS: 

stackunderflow undefined 
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Index 


A_ 

Application 

basic requirements, 3-3 to 3-4 
building, 3-9 to 3-11 
developing typical, 3-1 to 3-3 
sample 

See Sample applications 

B_ 

Basic tasks, summary, 3-13 to 3-14 
Bit gravity, 4-4 
Buffering, 4-1 

c_ 

Client Library, 2-2 
header files, 5-1 
naming conventions 

See Naming conventions, Client Library 
Client Library routines, 5-4 to 5-15 
clientsync operator, 6-3 
Clipping path, 4-4 
Color, using, 4-7 to 4-11 
Color cube 

See Color, using 
Colormap 

allocating entries in, 4-8 to 4-10 
See also setrgbXactual operator 
See Color, using 
Compiling 

See Application, building 
Context, 2-2 to 2-3 
color attributes 

obtaining, 6-4 
setting, 6-5 
creating 

execution context, 5-7, 5-9 
text context, 5-5 
finding 

See DPSContext handle, finding 
pausing, 6-3 
sharing, 4-7 
unfreezing, 5-14 
XID, finding, 5-14 
Context record, 2-3 
Context status events, 2-4 

See also XDPSRegisterStatusProc routine and 
XDPSSetStatusMask routine 
Context status mask, 2-4 


Context status mask (Cont.) 

See also XDPSSetStatusMask routine 
Coordinates, converting, 4-2 to 4-3 
Coordinate systems, 2-4 to 2-7 
Current context, 2-4 
See also Context 

currentXgcdrawablecolor operator, 6-4 
currentXgcdrawable operator, 6-3 
currentXoffset operator, 6-4 

D_ 

Default text backstop 

See DPSDefaultTextBackstop routine 
Default user space origin 
See User space origin 
Documentation, summary of, 1-2 to 1-3 
DPSChangeEncoding routine, 5-4 
DPSContextFromContextID routine, 5-5 
DPSContext handle, 2-3 
finding, 5-5, 5-6, 5-7, 5-11 
DPSContextRec data type 
See Context record 
DPSCreateTextContext routine, 5-5 
DPSDefaultTextBackstop routine, 5-6 
DPSNewUserObjectlndex routine, 5-6 
DPSSpace handle 
finding, 5-13, 5-14 
dpsXclient.h file 

See System-specific header file 
Drawable 

See also Window 
setting 

See setXgcdrawable operator 

E__ 

Encoding, PostScript language, 4-1,5-4 
Example applications 
See Sample applications 
examplemain sample application, 3-4 to 3-11 
Execution context 
See Context 

F_ 

Files, accessing, 4-2 
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G 


GC 

See X Graphic Context 
Graphic Context 

See X Graphic Context 
Graphics state, 2-3, 6-4 
Gray ramp 

See Color, using 


H 


Header files 

See also Application, building 
See Client Library, header files 


Space (Cont.) 
finding 

See DPSSpace handle, finding, 5-14 
sharing, 4-7 
Synchronization 

client and context, 4-7 
Display PostScript System and X, 4-6 
System-specific header file, 5-1 

T 


Text context 
See Context 


u 


■ User object index, new 

[ _ See DPSNewUserObjectlndex routine 

Identifiers, 2-4 User space coordinate system 

Imaging model, 1-1 See Coordinate systems 

Input, defined, 2-3 User space origin, 2-5 

obtaining, 6-3, 6-4 

I setting, 6-4, 6-5 


Linking 

See Application, building 


M_ 

Makefile, sample 

See Application, building 


V_ 

Virtual memory 
See VM 
VM, 2-4 

W 


N 


Window, resizing, 4-3 to 4-6 


Naming conventions, Client Library, 5-3 


x 


o_ 

Operators, 6-1 to 6-5 

See also individual operator names 
Origin 

See also User space origin 
See Coordinate systems 
Output, defined, 2-3 

P_ 

Pixel value 

See Color, using 
PostScript interpreter, 2-1 
PostScript language encoding 

See Encoding, PostScript language 
PostScript language imaging, 1-1 
pswrap translation program, 2-2 

s 


X coordinate system 

See Coordinate systems 
XDPSContextFromSharedID routine, 5-6 
XDPSContextFromXID routine, 5-7 
XDPSCreateContext routine, 5-7 
XDPSCreateSimpIeContext routine, 5-9 
XDPSFindContext routine, 5-11 
XDPSRegisterStatusProc routine, 5-11 
XDPSSetStatusMask routine, 5-12 
XDPSSpaceFromSharedID routine, 5-13 
XDPSSpaceFromXID routine, 5-14 
XDPSUnfreezeContext routine, 5-14 
XDPSXIDFromContext routine, 5-14 
XDPSXIDFromSpace routine, 5-14 
X Graphic Context, 2-3 
setting, 6-4, 6-5 
X-specific Operators 
See Operators 
XStandardColormap 
See Color, using 


Sample applications 
running, 3-13 
summary, 3-12 
setrgbXactual operator, 6-4 
setXgcdrawablecoIor operator, 6-5 
setXgcdrawable operator, 6-4 
Singleops, 5-2 to 5-3 
Space, 2-4 
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How to Order Additional Documentation 


Technical Support 

If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 
your electronic, telephone, or direct mail order. 


Electronic Orders 

To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400- 
baud modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location 

Continental USA, 
Alaska, or Hawaii 

Puerto Rico 
Canada 


International 

Internal* 


Call 

800-DIGITAL 

809-754-7575 

800-267-6215 


Contact 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, New Hampshire 03061 

Local Digital Subsidiary 

Digital Equipment of Canada 

Attn: DECdirect Operations KA02/2 

P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 

Local Digital subsidiary or 
approved distributor 

SSB Order Processing - WMO/E15 
or 

Software Supply Business 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


* For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 






Reader’s Comments 


ULTRIX Worksystem Software 

Guide to Developing Applications for the 
Display PostScript® System 
AA-PAJUA-TE 


Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


Please rate this manual: 

Excellent 

Good 

Fair 

Poor 

Accuracy (software works as manual says) 

□ 

□ 

□ 

□ 

Completeness (enough information) 

□ 

□ 

□ 

□ 

Clarity (easy to understand) 

□ 

□ 

□ 

□ 

Organization (structure of subject matter) 

□ 

□ 

□ 

□ 

Figures (useful) 

□ 

□ 

□ 

□ 

Examples (useful) 

□ 

□ 

□ 

□ 

Index (ability to find topic) 

□ 

□ 

□ 

□ 

Page layout (easy to find information) 

□ 

□ 

□ 

□ 


What would you like to see more/less of? 


What do you like best about this manual? 


What do you like least about this manual? 


Please list errors you have found in this manual: 
Page Description 


Additional comments or suggestions to improve this manual: 
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